IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/a_man/cat7/log.z/log

Text File | 2002-10-03 | 20.4 KB | 260 lines

lllloooogggg((((7777))))                                                                  lllloooogggg((((7777))))



NNNNAAAAMMMMEEEE
     _llll_oooo_gggg - interface to STREAMS error logging and event tracing

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _llll_oooo_gggg is a STREAMS software device driver that provides an interface for
     console logging and for the STREAMS error logging and event tracing
     processes [_ssss_tttt_rrrr_eeee_rrrr_rrrr(1M), _ssss_tttt_rrrr_aaaa_cccc_eeee(1M)].  _llll_oooo_gggg presents two separate
     interfaces: a function call interface in the kernel through which STREAMS
     drivers and modules submit _llll_oooo_gggg messages; and a subset of _iiii_oooo_cccc_tttt_llll(2) system
     calls and STREAMS messages for interaction with a user level console
     logger, an error logger, a trace logger, or processes that need to submit
     their own _llll_oooo_gggg messages.

   KKKKeeeerrrrnnnneeeellll IIIInnnntttteeeerrrrffffaaaacccceeee
     _llll_oooo_gggg messages are generated within the kernel by calls to the function
     _ssss_tttt_rrrr_llll_oooo_gggg:

          _ssss_tttt_rrrr_llll_oooo_gggg_((((_mmmm_iiii_dddd_,,,, _ssss_iiii_dddd_,,,, _llll_eeee_vvvv_eeee_llll_,,,, _ffff_llll_aaaa_gggg_ssss_,,,, _ffff_mmmm_tttt_,,,, _aaaa_rrrr_gggg_1111_,,,, _...._...._...._))))
          _ssss_hhhh_oooo_rrrr_tttt _mmmm_iiii_dddd_,,,, _ssss_iiii_dddd_;;;;
          _cccc_hhhh_aaaa_rrrr _llll_eeee_vvvv_eeee_llll_;;;;
          _uuuu_ssss_hhhh_oooo_rrrr_tttt _ffff_llll_aaaa_gggg_ssss_;;;;
          _cccc_hhhh_aaaa_rrrr _****_ffff_mmmm_tttt_;;;;
          _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _aaaa_rrrr_gggg_1111_;;;;

     Required definitions are contained in _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_llll_oooo_gggg_...._hhhh_>>>>, _<<<<_ssss_yyyy_ssss_////_llll_oooo_gggg_...._hhhh_>>>>, and
     _<<<<_ssss_yyyy_ssss_////_ssss_yyyy_ssss_llll_oooo_gggg_...._hhhh_>>>>.  _m_i_d is the STREAMS module id number for the module or
     driver submitting the _llll_oooo_gggg message.  _s_i_d is an internal sub-id number
     usually used to identify a particular minor device of a driver.  _l_e_v_e_l is
     a tracing level that allows for selective screening out of low priority
     messages from the tracer.  _f_l_a_g_s are any combination of _SSSS_LLLL______EEEE_RRRR_RRRR_OOOO_RRRR (the
     message is for the error logger), _SSSS_LLLL______TTTT_RRRR_AAAA_CCCC_EEEE (the message is for the
     tracer), _SSSS_LLLL______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE (the message is for the console logger), _SSSS_LLLL______FFFF_AAAA_TTTT_AAAA_LLLL
     (advisory notification of a fatal error), and _SSSS_LLLL______NNNN_OOOO_TTTT_IIII_FFFF_YYYY (request that a
     copy of the message be mailed to the system administrator).  _f_m_t is a
     _pppp_rrrr_iiii_nnnn_tttt_ffff(3S) style format string, except that %s, %e, %E, %g, and %G
     conversion specifications are not handled.  Up to _NNNN_LLLL_OOOO_GGGG_AAAA_RRRR_GGGG_SSSS (currently 3)
     numeric or character arguments can be provided.

   UUUUsssseeeerrrr IIIInnnntttteeeerrrrffffaaaacccceeee
     _llll_oooo_gggg is opened via the _cccc_llll_oooo_nnnn_eeee interface, _////_dddd_eeee_vvvv_////_llll_oooo_gggg.  Each open of _////_dddd_eeee_vvvv_////_llll_oooo_gggg
     obtains a separate stream to _llll_oooo_gggg.  In order to receive _llll_oooo_gggg messages, a
     process must first notify _llll_oooo_gggg whether it is an error logger, trace
     logger, or console logger via a STREAMS _IIII______SSSS_TTTT_RRRR _iiii_oooo_cccc_tttt_llll call (see below).
     For the console logger, the _IIII______SSSS_TTTT_RRRR _iiii_oooo_cccc_tttt_llll has an _iiii_cccc______cccc_mmmm_dddd field of _IIII______CCCC_OOOO_NNNN_SSSS_LLLL_OOOO_GGGG,
     with no accompanying data.  For the error logger, the _IIII______SSSS_TTTT_RRRR _iiii_oooo_cccc_tttt_llll has an
     _iiii_cccc______cccc_mmmm_dddd field of _IIII______EEEE_RRRR_RRRR_LLLL_OOOO_GGGG, with no accompanying data.  For the trace
     logger, the _iiii_oooo_cccc_tttt_llll has an _iiii_cccc______cccc_mmmm_dddd field of _IIII______TTTT_RRRR_CCCC_LLLL_OOOO_GGGG, and must be
     accompanied by a data buffer containing an array of one or more struct
     _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss elements.  Each _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss structure specifies an _m_i_d, _s_i_d, and
     _l_e_v_e_l from which message will be accepted.  _ssss_tttt_rrrr_llll_oooo_gggg will accept messages
     whose _m_i_d and _s_i_d exactly match those in the _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss structure, and
     whose level is less than or equal to the level given in the _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss



                                                                        PPPPaaaaggggeeee 1111






lllloooogggg((((7777))))                                                                  lllloooogggg((((7777))))



     structure.  A value of -1 in any of the fields of the _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss structure
     indicates that any value is accepted for that field.

     Once the logger process has identified itself via the _iiii_oooo_cccc_tttt_llll call, _llll_oooo_gggg
     will begin sending up messages subject to the restrictions noted above.
     These messages are obtained via the _gggg_eeee_tttt_mmmm_ssss_gggg_((((_2222_)))) system call.  The control
     part of this message contains a _llll_oooo_gggg______cccc_tttt_llll structure, which specifies the
     _m_i_d, _s_i_d, _l_e_v_e_l, _f_l_a_g_s, time in ticks since boot that the message was
     submitted, the corresponding time in seconds since Jan. 1, 1970, a
     sequence number, and a priority.  The time in seconds since 1970 is
     provided so that the date and time of the message can be easily computed,
     and the time in ticks since boot is provided so that the relative timing
     of _llll_oooo_gggg messages can be determined.

     The priority is comprised of a priority code and a facility code, found
     in _<<<<_ssss_yyyy_ssss_////_ssss_yyyy_ssss_llll_oooo_gggg_...._hhhh_>>>>.  If _SSSS_LLLL______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE is set in _f_l_a_g_s, the priority code is
     set as follows. If _SSSS_LLLL______WWWW_AAAA_RRRR_NNNN is set, the priority code is set to
     _LLLL_OOOO_GGGG______WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG.  If _SSSS_LLLL______FFFF_AAAA_TTTT_AAAA_LLLL is set, the priority code is set to _LLLL_OOOO_GGGG______CCCC_RRRR_IIII_TTTT.
     If _SSSS_LLLL______EEEE_RRRR_RRRR_OOOO_RRRR is set, the priority code is set to _LLLL_OOOO_GGGG______EEEE_RRRR_RRRR.  If _SSSS_LLLL______NNNN_OOOO_TTTT_EEEE is
     set, the priority code is set to _LLLL_OOOO_GGGG______NNNN_OOOO_TTTT_IIII_CCCC_EEEE.  If _SSSS_LLLL______TTTT_RRRR_AAAA_CCCC_EEEE is set, the
     priority code is set to _LLLL_OOOO_GGGG______DDDD_EEEE_BBBB_UUUU_GGGG.  If only _SSSS_LLLL______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE is set, the
     priority code is set to _LLLL_OOOO_GGGG______IIII_NNNN_FFFF_OOOO. Messages originating from the kernel
     have the facility code set to _LLLL_OOOO_GGGG______KKKK_EEEE_RRRR_NNNN. Most messages originating from
     user processes will have the facility code set to _LLLL_OOOO_GGGG______UUUU_SSSS_EEEE_RRRR.

     Different sequence numbers are maintained for the error and trace logging
     streams, and are provided so that gaps in the sequence of messages can be
     determined (during times of high message traffic some messages may not be
     delivered by the logger to avoid hogging system resources).  The data
     part of the message contains the unexpanded text of the format string
     (null terminated), followed by _NNNN_LLLL_OOOO_GGGG_AAAA_RRRR_GGGG_SSSS words for the arguments to the
     format string, aligned on the first word boundary following the format
     string.

     A process may also send a message of the same structure to _llll_oooo_gggg, even if
     it is not an error or trace logger.  The only fields of the _llll_oooo_gggg______cccc_tttt_llll
     structure in the control part of the message that are accepted are the
     _l_e_v_e_l, _f_l_a_g_s, and _p_r_i fields; all other fields are filled in by _llll_oooo_gggg
     before being forwarded to the appropriate logger.  The data portion must
     contain a null terminated format string, and any arguments (up to
     _NNNN_LLLL_OOOO_GGGG_AAAA_RRRR_GGGG_SSSS) must be packed one word each, on the next word boundary
     following the end of the format string.

     _EEEE_NNNN_XXXX_IIII_OOOO is returned for _IIII______TTTT_RRRR_CCCC_LLLL_OOOO_GGGG _iiii_oooo_cccc_tttt_lllls without any _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss structures,
     or for any unrecognized _IIII______SSSS_TTTT_RRRR _iiii_oooo_cccc_tttt_llll calls.  Incorrectly formatted _llll_oooo_gggg
     messages sent to the driver by a user process are silently ignored (no
     error results).

     Processes that wish to write a message to the console logger may direct
     their output to _////_dddd_eeee_vvvv_////_cccc_oooo_nnnn_ssss_llll_oooo_gggg, using either _wwww_rrrr_iiii_tttt_eeee(2) or _pppp_uuuu_tttt_mmmm_ssss_gggg(2).





                                                                        PPPPaaaaggggeeee 2222






lllloooogggg((((7777))))                                                                  lllloooogggg((((7777))))



EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     Example of _IIII______EEEE_RRRR_RRRR_LLLL_OOOO_GGGG notification.

          _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_iiii_oooo_cccc_tttt_llll _iiii_oooo_cccc_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______cccc_mmmm_dddd _==== _IIII______EEEE_RRRR_RRRR_LLLL_OOOO_GGGG_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______tttt_iiii_mmmm_oooo_uuuu_tttt _==== _0000_;;;;  _////_**** _dddd_eeee_ffff_aaaa_uuuu_llll_tttt _tttt_iiii_mmmm_eeee_oooo_uuuu_tttt _((((_1111_5555 _ssss_eeee_cccc_ssss_...._)))) _****_////
          _iiii_oooo_cccc_...._iiii_cccc______llll_eeee_nnnn _==== _0000_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______dddd_pppp _==== _NNNN_UUUU_LLLL_LLLL_;;;;
          _iiii_oooo_cccc_tttt_llll_((((_llll_oooo_gggg_,,,, _IIII______SSSS_TTTT_RRRR_,,,, _&&&&_iiii_oooo_cccc_))))_;;;;

     Example of _IIII______TTTT_RRRR_CCCC_LLLL_OOOO_GGGG notification.

          _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss _tttt_iiii_dddd_[[[[_2222_]]]]_;;;;
          _tttt_iiii_dddd_[[[[_0000_]]]]_...._tttt_iiii______mmmm_iiii_dddd _==== _2222_;;;;
          _tttt_iiii_dddd_[[[[_0000_]]]]_...._tttt_iiii______ssss_iiii_dddd _==== _0000_;;;;
          _tttt_iiii_dddd_[[[[_0000_]]]]_...._tttt_iiii______llll_eeee_vvvv_eeee_llll _==== _1111_;;;;
          _tttt_iiii_dddd_[[[[_1111_]]]]_...._tttt_iiii______mmmm_iiii_dddd _==== _1111_0000_0000_2222_;;;;
          _tttt_iiii_dddd_[[[[_1111_]]]]_...._tttt_iiii______ssss_iiii_dddd _==== _----_1111_;;;; _////_**** _aaaa_nnnn_yyyy _ssss_uuuu_bbbb_----_iiii_dddd _wwww_iiii_llll_llll _bbbb_eeee _aaaa_llll_llll_oooo_wwww_eeee_dddd _****_////
          _tttt_iiii_dddd_[[[[_1111_]]]]_...._tttt_iiii______llll_eeee_vvvv_eeee_llll _==== _----_1111_;;;;    _////_**** _aaaa_nnnn_yyyy _llll_eeee_vvvv_eeee_llll _wwww_iiii_llll_llll _bbbb_eeee _aaaa_llll_llll_oooo_wwww_eeee_dddd _****_////
          _iiii_oooo_cccc_...._iiii_cccc______cccc_mmmm_dddd _==== _IIII______TTTT_RRRR_CCCC_LLLL_OOOO_GGGG_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______tttt_iiii_mmmm_oooo_uuuu_tttt _==== _0000_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______llll_eeee_nnnn _==== _2222 _**** _ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_rrrr_aaaa_cccc_eeee______iiii_dddd_ssss_))))_;;;;
          _iiii_oooo_cccc_...._iiii_cccc______dddd_pppp _==== _((((_cccc_hhhh_aaaa_rrrr _****_))))_tttt_iiii_dddd_;;;;
          _iiii_oooo_cccc_tttt_llll_((((_llll_oooo_gggg_,,,, _IIII______SSSS_TTTT_RRRR_,,,, _&&&&_iiii_oooo_cccc_))))_;;;;

     Example of submitting a _llll_oooo_gggg message (no arguments).

          _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _cccc_tttt_llll_,,,, _dddd_aaaa_tttt_;;;;
          _ssss_tttt_rrrr_uuuu_cccc_tttt _llll_oooo_gggg______cccc_tttt_llll _llll_cccc_;;;;
          _cccc_hhhh_aaaa_rrrr _****_mmmm_eeee_ssss_ssss_aaaa_gggg_eeee _==== _""""_DDDD_oooo_nnnn_''''_tttt _ffff_oooo_rrrr_gggg_eeee_tttt _tttt_oooo _pppp_iiii_cccc_kkkk _uuuu_pppp _ssss_oooo_mmmm_eeee _mmmm_iiii_llll_kkkk
                           _oooo_nnnn _tttt_hhhh_eeee _wwww_aaaa_yyyy _hhhh_oooo_mmmm_eeee_""""_;;;;
          _cccc_tttt_llll_...._llll_eeee_nnnn _==== _cccc_tttt_llll_...._mmmm_aaaa_xxxx_llll_eeee_nnnn _==== _ssss_iiii_zzzz_eeee_oooo_ffff_((((_llll_cccc_))))_;;;;
          _cccc_tttt_llll_...._bbbb_uuuu_ffff _==== _((((_cccc_hhhh_aaaa_rrrr _****_))))_&&&&_llll_cccc_;;;;
          _dddd_aaaa_tttt_...._llll_eeee_nnnn _==== _dddd_aaaa_tttt_...._mmmm_aaaa_xxxx_llll_eeee_nnnn _==== _ssss_tttt_rrrr_llll_eeee_nnnn_((((_mmmm_eeee_ssss_ssss_aaaa_gggg_eeee_))))_;;;;
          _dddd_aaaa_tttt_...._bbbb_uuuu_ffff _==== _mmmm_eeee_ssss_ssss_aaaa_gggg_eeee_;;;;
          _llll_cccc_...._llll_eeee_vvvv_eeee_llll _==== _0000_;;;;
          _llll_cccc_...._ffff_llll_aaaa_gggg_ssss _==== _SSSS_LLLL______EEEE_RRRR_RRRR_OOOO_RRRR_||||_SSSS_LLLL______NNNN_OOOO_TTTT_IIII_FFFF_YYYY_;;;;
          _pppp_uuuu_tttt_mmmm_ssss_gggg_((((_llll_oooo_gggg_,,,, _&&&&_cccc_tttt_llll_,,,, _&&&&_dddd_aaaa_tttt_,,,, _0000_))))_;;;;

FFFFIIIILLLLEEEESSSS
     _////_dddd_eeee_vvvv_////_llll_oooo_gggg
     _////_dddd_eeee_vvvv_////_cccc_oooo_nnnn_ssss_llll_oooo_gggg
     _<<<<_ssss_yyyy_ssss_////_llll_oooo_gggg_...._hhhh_>>>>
     _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_llll_oooo_gggg_...._hhhh_>>>>
     _<<<<_ssss_yyyy_ssss_////_ssss_yyyy_ssss_llll_oooo_gggg_...._hhhh_>>>>





                                                                        PPPPaaaaggggeeee 3333






lllloooogggg((((7777))))                                                                  lllloooogggg((((7777))))



SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _ssss_tttt_rrrr_aaaa_cccc_eeee(1M), _ssss_tttt_rrrr_eeee_rrrr_rrrr(1M), _gggg_eeee_tttt_mmmm_ssss_gggg(2), _iiii_nnnn_tttt_rrrr_oooo(2), _pppp_uuuu_tttt_mmmm_ssss_gggg(2), _wwww_rrrr_iiii_tttt_eeee(2),
     _cccc_llll_oooo_nnnn_eeee(7)

NNNNOOOOTTTTEEEESSSS
     The _llll_oooo_gggg driver high and low water marks are tunable via the master file.

















































                                                                        PPPPaaaaggggeeee 4444